<html>
    <head>
    <link rel="stylesheet" href="lmm.css" type="text/css" />
    </head>
<body class="lmm">
<!-- This file is part of the Lisp Machine Manual.  -*-Text-*- -->
<!-- Debugging: Various Debuggingc Aids -->

<div class='section' id='26.1'>26.1 Trace</div>
	The <!-- open: 1, close: 0 --><font class="italic">trace</font><!-- open: 1, close: 1 --> <!-- MATCHED MATCHED MATCHED --> facility allows the user to trace some functions.
When a function is traced, certain special actions will be taken when it is
called, and when it returns.  The function <!-- open: 2, close: 1 --><font class="lisp">trace</font><!-- open: 2, close: 2 --> <!-- MATCHED MATCHED MATCHED --> allows the user to
specify this.

	The trace facility is closely compatible with Maclisp.
Although the functions of the trace system which are presented here are
really functions, they are implemented as special forms because that
is the way Maclisp did it.

	Alternatively, you can use the trace system by clicking "trace"
in the system menu, or by using the "meta-X trace" command in the editor.
This allows you to select the trace options from a menu instead of having
to remember the following syntax.

<div class='defspec' id='trace'><font class='exdent'><font class='funcname' id='trace'>trace</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent -->	A <!-- open: 3, close: 2 --><font class="lisp">trace</font><!-- open: 3, close: 3 --> <!-- MATCHED MATCHED MATCHED --> form looks like:
<pre class='lisp'>
(trace <!-- open: 4, close: 3 --><font class="italic">spec-1</font><!-- open: 4, close: 4 --> <!-- MATCHED MATCHED MATCHED --> <!-- open: 5, close: 4 --><font class="italic">spec-2</font><!-- open: 5, close: 5 --> <!-- MATCHED MATCHED MATCHED --> ...)
</pre>

	A <!-- open: 6, close: 5 --><font class="italic">spec</font><!-- open: 6, close: 6 --> <!-- MATCHED MATCHED MATCHED --> may be either a symbol, which is interpreted as a function
name, or a list of the form <!-- open: 7, close: 6 --><font class="lisp">(<!-- open: 8, close: 6 --><font class="italic">function-name</font><!-- open: 8, close: 7 --> <!-- open: 9, close: 7 --><font class="italic">option-1</font><!-- open: 9, close: 8 --> <!-- open: 10, close: 8 --><font class="italic">option-2</font><!-- open: 10, close: 9 --> ...)</font><!-- open: 10, close: 10 --> <!-- MATCHED MATCHED MATCHED -->.
If <!-- open: 11, close: 10 --><font class="italic">spec</font><!-- open: 11, close: 11 --> <!-- MATCHED MATCHED MATCHED --> is a symbol, it is the same as giving the function name with
no options.  Some options take "arguments", which should be given immediately
following the option name.
</div>

	The following options exist:
<table>
<tr valign='top'><td colspan='2'><font class='lisp'> :break <!-- open: 12, close: 11 --><font class="italic">pred</font><!-- open: 12, close: 12 --> <!-- MATCHED MATCHED MATCHED --></font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>Causes a breakpoint to be entered after printing
the entry trace information but before applying the traced function to its
arguments, if and only if <!-- open: 13, close: 12 --><font class="italic">pred</font><!-- open: 13, close: 13 --> <!-- MATCHED MATCHED MATCHED --> evaluates to non-<!-- open: 14, close: 13 --><font class="lisp">nil</font><!-- open: 14, close: 14 --> <!-- MATCHED MATCHED MATCHED -->.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> :exitbreak <!-- open: 15, close: 14 --><font class="italic">pred</font><!-- open: 15, close: 15 --> <!-- MATCHED MATCHED MATCHED --></font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>This is just like <!-- open: 16, close: 15 --><font class="lisp">break</font><!-- open: 16, close: 16 --> <!-- MATCHED MATCHED MATCHED --> except that the
breakpoint is entered after the function has been executed and the exit trace information
has been printed, but before control returns.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> :step</font></td><td>Causes the function to be single-stepped whenever it is called.
See the documentation on the step facility below.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> :entrycond <!-- open: 17, close: 16 --><font class="italic">pred</font><!-- open: 17, close: 17 --> <!-- MATCHED MATCHED MATCHED --></font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>Causes trace information to be printed on function
entry only if <!-- open: 18, close: 17 --><font class="italic">pred</font><!-- open: 18, close: 18 --> <!-- MATCHED MATCHED MATCHED --> evaluates to non-<!-- open: 19, close: 18 --><font class="lisp">nil</font><!-- open: 19, close: 19 --> <!-- MATCHED MATCHED MATCHED -->.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> :exitcond <!-- open: 20, close: 19 --><font class="italic">pred</font><!-- open: 20, close: 20 --> <!-- MATCHED MATCHED MATCHED --></font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>Causes trace information to be printed on function
exit only if <!-- open: 21, close: 20 --><font class="italic">pred</font><!-- open: 21, close: 21 --> <!-- MATCHED MATCHED MATCHED --> evaluates to non-<!-- open: 22, close: 21 --><font class="lisp">nil</font><!-- open: 22, close: 22 --> <!-- MATCHED MATCHED MATCHED -->.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> :cond <!-- open: 23, close: 22 --><font class="italic">pred</font><!-- open: 23, close: 23 --> <!-- MATCHED MATCHED MATCHED --></font></td><td>This specifies both <!-- open: 24, close: 23 --><font class="lisp">exitcond</font><!-- open: 24, close: 24 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 25, close: 24 --><font class="lisp">entrycond</font><!-- open: 25, close: 25 --> <!-- MATCHED MATCHED MATCHED -->
together.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> :wherein <!-- open: 26, close: 25 --><font class="italic">function</font><!-- open: 26, close: 26 --> <!-- MATCHED MATCHED MATCHED --></font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>Causes the function to be traced only when called, directly or indirectly,
from the specified function <!-- open: 27, close: 26 --><font class="italic">function</font><!-- open: 27, close: 27 --> <!-- MATCHED MATCHED MATCHED -->.  One can give several trace specs to
<!-- open: 28, close: 27 --><font class="lisp">trace</font><!-- open: 28, close: 28 --> <!-- MATCHED MATCHED MATCHED -->, all specifying the same function but with different <!-- open: 29, close: 28 --><font class="lisp">wherein</font><!-- open: 29, close: 29 --> <!-- MATCHED MATCHED MATCHED -->
options, so that the function is traced in different ways when called from
different functions.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> :argpdl <!-- open: 30, close: 29 --><font class="italic">pdl</font><!-- open: 30, close: 30 --> <!-- MATCHED MATCHED MATCHED --></font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>This specifies a symbol <!-- open: 31, close: 30 --><font class="italic">pdl</font><!-- open: 31, close: 31 --> <!-- MATCHED MATCHED MATCHED -->, whose value is
initially set to <!-- open: 32, close: 31 --><font class="lisp">nil</font><!-- open: 32, close: 32 --> <!-- MATCHED MATCHED MATCHED --> by <!-- open: 33, close: 32 --><font class="lisp">trace</font><!-- open: 33, close: 33 --> <!-- MATCHED MATCHED MATCHED -->.  When the function is traced, a
list of the current recursion level for the function, the function's
name, and a list of arguments is consed onto the <!-- open: 34, close: 33 --><font class="italic">pdl</font><!-- open: 34, close: 34 --> <!-- MATCHED MATCHED MATCHED --> when the
function is entered, and cdr'ed back off when the function is exited.
The <!-- open: 35, close: 34 --><font class="italic">pdl</font><!-- open: 35, close: 35 --> <!-- MATCHED MATCHED MATCHED --> can be inspected from within a breakpoint, for example, and
used to determine the very recent history of the function. This option
can be used with or without printed trace output.  Each function can be
given its own pdl, or one pdl may serve several functions.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> :entryprint <!-- open: 36, close: 35 --><font class="italic">form</font><!-- open: 36, close: 36 --> <!-- MATCHED MATCHED MATCHED --></font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>The <!-- open: 37, close: 36 --><font class="italic">form</font><!-- open: 37, close: 37 --> <!-- MATCHED MATCHED MATCHED --> is evaluated and the value is included in the trace message
for calls to the function.  You can give this option more than once, and
all the values will appear, preceded by <!-- open: 38, close: 37 --><font class="lisp">\\</font><!-- open: 38, close: 38 --> <!-- MATCHED MATCHED MATCHED -->.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> :exitprint <!-- open: 39, close: 38 --><font class="italic">form</font><!-- open: 39, close: 39 --> <!-- MATCHED MATCHED MATCHED --></font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>The <!-- open: 40, close: 39 --><font class="italic">form</font><!-- open: 40, close: 40 --> <!-- MATCHED MATCHED MATCHED --> is evaluated and the value is included in the trace message
for returns from the function.  You can give this option more than once, and
all the values will appear, preceded by <!-- open: 41, close: 40 --><font class="lisp">\\</font><!-- open: 41, close: 41 --> <!-- MATCHED MATCHED MATCHED -->.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> :print <!-- open: 42, close: 41 --><font class="italic">form</font><!-- open: 42, close: 42 --> <!-- MATCHED MATCHED MATCHED --></font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>The <!-- open: 43, close: 42 --><font class="italic">form</font><!-- open: 43, close: 43 --> <!-- MATCHED MATCHED MATCHED --> is evaluated and the value is included in the trace messages
for both calls to and returns from the function.  You can give this option more than once, and
all the values will appear, preceded by <!-- open: 44, close: 43 --><font class="lisp">\\</font><!-- open: 44, close: 44 --> <!-- MATCHED MATCHED MATCHED -->.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> :entry <!-- open: 45, close: 44 --><font class="italic">list</font><!-- open: 45, close: 45 --> <!-- MATCHED MATCHED MATCHED --></font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>This specifies a list of arbitrary forms whose
values are to be printed along with the usual entry-trace.  The list of
resultant values, when printed, is preceded by a <!-- open: 46, close: 45 --><font class="lisp">\\</font><!-- open: 46, close: 46 --> <!-- MATCHED MATCHED MATCHED --> to separate it
from the other information.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> :exit <!-- open: 47, close: 46 --><font class="italic">list</font><!-- open: 47, close: 47 --> <!-- MATCHED MATCHED MATCHED --></font></td><td>This is similar to <!-- open: 48, close: 47 --><font class="lisp">entry</font><!-- open: 48, close: 48 --> <!-- MATCHED MATCHED MATCHED -->, but specifies expressions
whose values are printed with the exit-trace.  Again, the list of
values printed is preceded by <!-- open: 49, close: 48 --><font class="lisp">\\</font><!-- open: 49, close: 49 --> <!-- MATCHED MATCHED MATCHED -->.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> :arg :value :both nil</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>These specify which of the usual trace
printout should be enabled.  If <!-- open: 50, close: 49 --><font class="lisp">arg</font><!-- open: 50, close: 50 --> <!-- MATCHED MATCHED MATCHED --> is specified, then on function
entry the name of the function and the values of its arguments will be
printed.  If <!-- open: 51, close: 50 --><font class="lisp">value</font><!-- open: 51, close: 51 --> <!-- MATCHED MATCHED MATCHED --> is specified, then on function exit the returned
value(s) of the function will be printed.  If <!-- open: 52, close: 51 --><font class="lisp">both</font><!-- open: 52, close: 52 --> <!-- MATCHED MATCHED MATCHED --> is specified,
both of these will be printed.  If <!-- open: 53, close: 52 --><font class="lisp">nil</font><!-- open: 53, close: 53 --> <!-- MATCHED MATCHED MATCHED --> is specified, neither will
be printed.  If none of these four options are specified the default is
to <!-- open: 54, close: 53 --><font class="lisp">both</font><!-- open: 54, close: 54 --> <!-- MATCHED MATCHED MATCHED -->.  If any further <!-- open: 55, close: 54 --><font class="italic">options</font><!-- open: 55, close: 55 --> <!-- MATCHED MATCHED MATCHED --> appear after one of these,
they will not be treated as options! Rather, they will be considered to
be arbitrary forms whose values are to be printed on entry and/or exit
to the function, along with the normal trace information. The values
printed will be preceded by a <!-- open: 56, close: 55 --><font class="lisp">//</font><!-- open: 56, close: 56 --> <!-- MATCHED MATCHED MATCHED -->, and follow any values specified
by <!-- open: 57, close: 56 --><font class="lisp">entry</font><!-- open: 57, close: 57 --> <!-- MATCHED MATCHED MATCHED --> or <!-- open: 58, close: 57 --><font class="lisp">exit</font><!-- open: 58, close: 58 --> <!-- MATCHED MATCHED MATCHED -->.  Note that since these options "swallow" all
following options, if one is given it should be the last option
specified.
</td></tr><!-- item_ --></table><!-- end table -->


If the variable <!-- open: 59, close: 58 --><font class="lisp">arglist</font><!-- open: 59, close: 59 --> <!-- MATCHED MATCHED MATCHED --> is used in any of the expressions given for
the <!-- open: 60, close: 59 --><font class="lisp">cond, break, entry, </font><!-- open: 60, close: 60 --> <!-- MATCHED MATCHED MATCHED -->or<!-- open: 61, close: 60 --><font class="lisp"> exit</font><!-- open: 61, close: 61 --> <!-- MATCHED MATCHED MATCHED --> options, or after the <!-- open: 62, close: 61 --><font class="lisp">arg,
value, both, </font><!-- open: 62, close: 62 --> <!-- MATCHED MATCHED MATCHED -->or<!-- open: 63, close: 62 --><font class="lisp"> nil</font><!-- open: 63, close: 63 --> <!-- MATCHED MATCHED MATCHED --> option, when those expressions are evaluated
the value of <!-- open: 64, close: 63 --><font class="lisp">arglist</font><!-- open: 64, close: 64 --> <!-- MATCHED MATCHED MATCHED --> will be bound to a list of the arguments
given to the traced function.  Thus 
<pre class='lisp'>
(trace (foo break (null (car arglist))))
</pre>
would cause a break in <!-- open: 65, close: 64 --><font class="lisp">foo</font><!-- open: 65, close: 65 --> <!-- MATCHED MATCHED MATCHED --> if and only if the first
argument to <!-- open: 66, close: 65 --><font class="lisp">foo</font><!-- open: 66, close: 66 --> <!-- MATCHED MATCHED MATCHED --> is <!-- open: 67, close: 66 --><font class="lisp">nil</font><!-- open: 67, close: 67 --> <!-- MATCHED MATCHED MATCHED -->.
<!-- open: 68, close: 67 --><font class="lisp">arglist</font><!-- open: 68, close: 68 --> <!-- MATCHED MATCHED MATCHED --> should have a colon, but it is omitted because this is
the name of a system function and therefore global.


Similarly, the variable <!-- open: 69, close: 68 --><font class="lisp">si:fnvalues</font><!-- open: 69, close: 69 --> <!-- MATCHED MATCHED MATCHED --> will
be a list of the resulting values of the traced function.  For obvious
reasons, this should only be used with the <!-- open: 70, close: 69 --><font class="lisp">exit</font><!-- open: 70, close: 70 --> <!-- MATCHED MATCHED MATCHED --> option.

The trace specifications may be "factored."  For example,
<pre class='lisp'>
(trace ((foo bar) wherein baz value))
<!-- open: 71, close: 70 --><font class="main">is equivalent to</font><!-- open: 71, close: 71 --> <!-- MATCHED MATCHED MATCHED -->
(trace (foo wherein baz value) (bar wherein baz value))
</pre>
Since a list as a function name is interpreted as a list of
functions, non-atomic function names (see <font color='red'>LINK:(</font>fdefine-fun))
are specified as follows:
<pre class='lisp'>
(trace (:function (:method foo-class bar) :break t))
</pre>

All output printed by trace can be ground into an indented,
readable format, by simply setting the variable <!-- open: 72, close: 71 --><font class="lisp">sprinter</font><!-- open: 72, close: 72 --> <!-- MATCHED MATCHED MATCHED --> to <!-- open: 73, close: 72 --><font class="lisp">t</font><!-- open: 73, close: 73 --> <!-- MATCHED MATCHED MATCHED -->.
Setting <!-- open: 74, close: 73 --><font class="lisp">sprinter</font><!-- open: 74, close: 74 --> <!-- MATCHED MATCHED MATCHED --> to <!-- open: 75, close: 74 --><font class="lisp">nil</font><!-- open: 75, close: 75 --> <!-- MATCHED MATCHED MATCHED --> changes the output back to use
the ordinary print function, which is faster and uses less
storage but is less readable for large list structures.
This is not yet supported.

<!-- open: 76, close: 75 --><font class="lisp">trace</font><!-- open: 76, close: 76 --> <!-- MATCHED MATCHED MATCHED --> returns as its value a list of names of all functions
traced; for any functions traced with the <!-- open: 77, close: 76 --><font class="lisp">wherein</font><!-- open: 77, close: 77 --> <!-- MATCHED MATCHED MATCHED -->
option, say <!-- open: 78, close: 77 --><font class="lisp">(trace (foo wherein bar))</font><!-- open: 78, close: 78 --> <!-- MATCHED MATCHED MATCHED -->, instead of putting
just <!-- open: 79, close: 78 --><font class="lisp">foo</font><!-- open: 79, close: 79 --> <!-- MATCHED MATCHED MATCHED --> in the list it puts in a 3-list <!-- open: 80, close: 79 --><font class="lisp">(foo wherein bar)</font><!-- open: 80, close: 80 --> <!-- MATCHED MATCHED MATCHED -->.

If you attempt to specify to <!-- open: 81, close: 80 --><font class="lisp">trace</font><!-- open: 81, close: 81 --> <!-- MATCHED MATCHED MATCHED --> a function already
being traced, <!-- open: 82, close: 81 --><font class="lisp">trace</font><!-- open: 82, close: 82 --> <!-- MATCHED MATCHED MATCHED --> calls <!-- open: 83, close: 82 --><font class="lisp">untrace</font><!-- open: 83, close: 83 --> <!-- MATCHED MATCHED MATCHED --> before setting up the new
trace.

It is possible to call <!-- open: 84, close: 83 --><font class="lisp">trace</font><!-- open: 84, close: 84 --> <!-- MATCHED MATCHED MATCHED --> with no arguments.  <!-- open: 85, close: 84 --><font class="lisp">(trace)</font><!-- open: 85, close: 85 --> <!-- MATCHED MATCHED MATCHED -->
evaluates to a list of all the functions currently
being traced.

<div class='defspec' id='untrace'><font class='exdent'><font class='funcname' id='untrace'>untrace</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent --><!-- open: 86, close: 85 --><font class="lisp">untrace</font><!-- open: 86, close: 86 --> <!-- MATCHED MATCHED MATCHED --> is used to undo the effects of <!-- open: 87, close: 86 --><font class="lisp">trace</font><!-- open: 87, close: 87 --> <!-- MATCHED MATCHED MATCHED --> and restore
functions to their normal, untraced state.  The argument
to <!-- open: 88, close: 87 --><font class="lisp">untrace</font><!-- open: 88, close: 88 --> <!-- MATCHED MATCHED MATCHED --> for a given function should be what
<!-- open: 89, close: 88 --><font class="lisp">trace</font><!-- open: 89, close: 89 --> <!-- MATCHED MATCHED MATCHED --> returned for it; i.e. if <!-- open: 90, close: 89 --><font class="lisp">trace</font><!-- open: 90, close: 90 --> <!-- MATCHED MATCHED MATCHED --> returned <!-- open: 91, close: 90 --><font class="lisp">foo</font><!-- open: 91, close: 91 --> <!-- MATCHED MATCHED MATCHED -->, use
<!-- open: 92, close: 91 --><font class="lisp">(untrace foo)</font><!-- open: 92, close: 92 --> <!-- MATCHED MATCHED MATCHED -->; if <!-- open: 93, close: 92 --><font class="lisp">trace</font><!-- open: 93, close: 93 --> <!-- MATCHED MATCHED MATCHED --> returned <!-- open: 94, close: 93 --><font class="lisp">(foo wherein bar)</font><!-- open: 94, close: 94 --> <!-- MATCHED MATCHED MATCHED --> use
<!-- open: 95, close: 94 --><font class="lisp">(untrace (foo wherein bar))</font><!-- open: 95, close: 95 --> <!-- MATCHED MATCHED MATCHED -->.  <!-- open: 96, close: 95 --><font class="lisp">untrace</font><!-- open: 96, close: 96 --> <!-- MATCHED MATCHED MATCHED --> will take multiple
specifications, e.g. <!-- open: 97, close: 96 --><font class="lisp">(untrace foo quux (bar wherein baz) fuphoo)</font><!-- open: 97, close: 97 --> <!-- MATCHED MATCHED MATCHED -->.
Calling <!-- open: 98, close: 97 --><font class="lisp">untrace</font><!-- open: 98, close: 98 --> <!-- MATCHED MATCHED MATCHED --> with no arguments will untrace all functions currently being traced.
</div>

Unlike Maclisp, if there is an error <!-- open: 99, close: 98 --><font class="lisp">trace</font><!-- open: 99, close: 99 --> <!-- MATCHED MATCHED MATCHED --> (or <!-- open: 100, close: 99 --><font class="lisp">untrace</font><!-- open: 100, close: 100 --> <!-- MATCHED MATCHED MATCHED -->) will
invoke
'c shaft you by invoking
the error system and give an English message, instead of returning
lists with question marks in them.  Also, the <!-- open: 101, close: 100 --><font class="lisp">remtrace</font><!-- open: 101, close: 101 --> <!-- MATCHED MATCHED MATCHED --> function
is not provided, since it is unnecessary.

<div class='defvar' id='trace-compile-flag'><font class='exdent'><font class='funcname' id='trace-compile-flag'>trace-compile-flag</font><font class="italic"> Variable</font><br></font><!-- end font_exdent -->If the value of <!-- open: 102, close: 101 --><font class="lisp">trace-compile-flag</font><!-- open: 102, close: 102 --> <!-- MATCHED MATCHED MATCHED --> is non-<!-- open: 103, close: 102 --><font class="lisp">nil</font><!-- open: 103, close: 103 --> <!-- MATCHED MATCHED MATCHED -->, the functions
created by <!-- open: 104, close: 103 --><font class="lisp">trace</font><!-- open: 104, close: 104 --> <!-- MATCHED MATCHED MATCHED --> will get compiled, allowing you to trace special
forms such as <!-- open: 105, close: 104 --><font class="lisp">cond</font><!-- open: 105, close: 105 --> <!-- MATCHED MATCHED MATCHED --> without interfering with the execution of the
tracing functions.  The default value of this flag is <!-- open: 106, close: 105 --><font class="lisp">nil</font><!-- open: 106, close: 106 --> <!-- MATCHED MATCHED MATCHED -->.
</div>

<div class='section' id='26.2'>26.2 The Stepper</div>
	The Step facility provides the ability to follow every step of
the evaluation of a form, and examine what is going on.  It is
analogous to a single-step proceed facility often found in
machine-language debuggers.  If your program is doing something
strange, and it isn't obvious how it's getting into its strange state,
then the stepper is for you.

<div class='subsection id='26.2.1''>26.2.1 How to Get Into the Stepper.</div>
	There are two ways to enter the stepper.  One is by use of the
<!-- open: 107, close: 106 --><font class="lisp">step</font><!-- open: 107, close: 107 --> <!-- MATCHED MATCHED MATCHED --> function.

<div class='defun' id='step'>
  <font class='exdent'>
    <font class='funcname'>step </font>
    <font class='italic' color='purple'>form</font>
  </font><br>
	This evaluates <!-- open: 108, close: 107 --><font class="italic">form</font><!-- open: 108, close: 108 --> <!-- MATCHED MATCHED MATCHED --> with single stepping.  It returns
the value of <!-- open: 109, close: 108 --><font class="italic">form</font><!-- open: 109, close: 109 --> <!-- MATCHED MATCHED MATCHED -->.
</div>

	For example, if you have a function named <!-- open: 110, close: 109 --><font class="lisp">foo</font><!-- open: 110, close: 110 --> <!-- MATCHED MATCHED MATCHED -->, and typical arguments
to it might be <!-- open: 111, close: 110 --><font class="lisp">t</font><!-- open: 111, close: 111 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 112, close: 111 --><font class="lisp">3</font><!-- open: 112, close: 112 --> <!-- MATCHED MATCHED MATCHED -->, you could say
<pre class='lisp'>
(step '(foo t 3))
</pre>
and the form <!-- open: 113, close: 112 --><font class="lisp">(foo t 3)</font><!-- open: 113, close: 113 --> <!-- MATCHED MATCHED MATCHED --> will be evaluated with single stepping.

	The other way to get into the stepper is to use the <!-- open: 114, close: 113 --><font class="lisp">step</font><!-- open: 114, close: 114 --> <!-- MATCHED MATCHED MATCHED --> option 
of <!-- open: 115, close: 114 --><font class="lisp">trace</font><!-- open: 115, close: 115 --> <!-- MATCHED MATCHED MATCHED --> (see <font color='red'>LINK:(</font>trace-fun)).  If a function is traced with the <!-- open: 116, close: 115 --><font class="lisp">step</font><!-- open: 116, close: 116 --> <!-- MATCHED MATCHED MATCHED --> option, then
whenever that function is called it will be single stepped.

	Note that any function to be stepped must be interpreted; that is, it
must be a lambda-expression.  Compiled code cannot be stepped by the stepper.

<div class='subsection id='26.2.2''>26.2.2 How to Use the Stepper</div>
	When evaluation is proceeding with single stepping, before any
form is evaluated, it is (partially) printed out, preceded by a forward
arrow (<!-- open: 117, close: 116 --><font class="lisp">&rarr;</font><!-- open: 117, close: 117 --> <!-- MATCHED MATCHED MATCHED -->) character  When a macro is expanded, the expansion is
printed out preceded by a double arrow (<!-- open: 118, close: 117 --><font class="lisp">&harr;</font><!-- open: 118, close: 118 --> <!-- MATCHED MATCHED MATCHED -->) character.  When a form
returns a value, the form and the values are printed out preceded by a
backwards arrow (<!-- open: 119, close: 118 --><font class="lisp">&larr;</font><!-- open: 119, close: 119 --> <!-- MATCHED MATCHED MATCHED -->) character; if there is more than one value being
returned, an and-sign (<!-- open: 120, close: 119 --><font class="lisp">&and;</font><!-- open: 120, close: 120 --> <!-- MATCHED MATCHED MATCHED -->) character is printed between the values. 

	Since the forms may be very long, the stepper does not print all
of a form; it truncates the printed representation after a certain number
of characters.  Also, to show the recursion pattern of who calls whom in
a graphic fashion, it indents each form proportionally to its level
of recursion.

	After the stepper prints any of these things, it waits for a
command from the user.  There are several commands to tell the stepper
how to proceed, or to look at what is happening. The commands are:
<table>
<tr valign='top'><td colspan='2'><font class='lisp'> Control-N (Next)</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>Step to the Next thing.  The stepper continues until the next thing
to print out, and it accepts another command.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> Space</font></td><td>Go to the next thing at this level.  In other words, continue to
evaluate at this level, but don't step anything at lower levels.  This is a good
way to skip over parts of the evaluation that don't interest you.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> Control-U (Up)</font></td><td>Continue evaluating until we go up one level.  This is like
the space command, only more so; it skips over anything on the current level
as well as lower levels.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> Control-X (eXit)</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>Exit; finish evaluating without any more stepping.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> Control-T (Type)</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>Retype the current form in full (without truncation).
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> Control-G (Grind)</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>Grind (i.e. prettyprint) the current form.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> Control-E (Editor)</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>Editor escape (enter the Eine editor).
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> Control-B (Breakpoint)</font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>Breakpoint.  This command puts you into a breakpoint (i.e.
a read-eval-print loop) from which you can examine the values of
variables and other aspects of the current environment.  From
within this loop, the following variables are available:
<table>
</td></tr>
<tr valign='top'>
<td><font class='lisp'> step-form</font></td><td>which is the current form.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> step-values</font></td><td>which is the list of returned values.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> step-value</font></td><td>which is the first returned value.
</td></tr><!-- item_ --></table><!-- end table -->

If you change the values of these variables, it will work.
<tr valign='top'>
<td><font class='lisp'> Control-L</font></td><td>Clear the screen and redisplay the last 10. pending forms (forms
which are being evaluated).
<tr valign='top'>
<td><font class='lisp'> Meta-L</font></td><td>Like Control-L, but doesn't clear the screen.
<tr valign='top'>
<td><font class='lisp'> Control-Meta-L</font></td><td>Like Control-L, but redisplays all pending forms.
<tr valign='top'>
<td><font class='lisp'> ? or Help</font></td><td>Prints documentation on these commands.
</td></tr><!-- item_ --></table><!-- end table -->

	It is strongly suggested that you write some little function
and try the stepper on it.  If you get a feel for what the stepper does
and how it works, you will be able to tell when it is the right thing to use
to find bugs.

<div class='section' id='26.3'>26.3 The MAR</div>
	The MAR facility allows any word or contiguous set of words to
be monitored constantly, and can cause an error if the words are
referenced in a specified manner.  The name MAR is from the similar
device on the ITS PDP-10's; it is an acronym for "Memory Address
Register".  The MAR checking is done by the Lisp Machine's memory
management hardware, and so the speed of general execution when the MAR is
enabled is not significantly slowed down.  However, the speed of accessing
pages of memory containing the locations being checked is slowed down, since every
reference involves a microcode trap.

	These are the functions that control the MAR:

<div class='defun' id='set-mar'>
  <font class='exdent'>
    <font class='funcname'>set-mar </font>
    <font class='italic' color='purple'>location cycle-type &optional n-words</font>
  </font><br>
	The <!-- open: 121, close: 120 --><font class="lisp">set-mar</font><!-- open: 121, close: 121 --> <!-- MATCHED MATCHED MATCHED --> function clears any previous setting of the
MAR, and sets the MAR on <!-- open: 122, close: 121 --><font class="italic">n-words</font><!-- open: 122, close: 122 --> <!-- MATCHED MATCHED MATCHED --> words, starting at <!-- open: 123, close: 122 --><font class="italic">location</font><!-- open: 123, close: 123 --> <!-- MATCHED MATCHED MATCHED -->.
<!-- open: 124, close: 123 --><font class="italic">location</font><!-- open: 124, close: 124 --> <!-- MATCHED MATCHED MATCHED --> may be any object.  <!-- open: 125, close: 124 --><font class="italic">n-words</font><!-- open: 125, close: 125 --> <!-- MATCHED MATCHED MATCHED --> currently defaults to 1,
but eventually it will default to the size of the object.
<!-- open: 126, close: 125 --><font class="italic">cycle-type</font><!-- open: 126, close: 126 --> <!-- MATCHED MATCHED MATCHED --> says under what conditions to trap.  <!-- open: 127, close: 126 --><font class="lisp">:read</font><!-- open: 127, close: 127 --> <!-- MATCHED MATCHED MATCHED --> means that
only reading the location should cause an error, <!-- open: 128, close: 127 --><font class="lisp">:write</font><!-- open: 128, close: 128 --> <!-- MATCHED MATCHED MATCHED --> means that
only writing the location should, <!-- open: 129, close: 128 --><font class="lisp">t</font><!-- open: 129, close: 129 --> <!-- MATCHED MATCHED MATCHED --> means that both should.
To set the MAR on the value of a variable, use
<pre class='lisp'>
(set-mar (value-cell-location <!-- open: 130, close: 129 --><font class="italic">symbol</font><!-- open: 130, close: 130 --> <!-- MATCHED MATCHED MATCHED -->) :write)
</pre>
</div>

<div class='defun' id='clear-mar'>
  <font class='exdent'>
    <font class='funcname'>clear-mar </font>
    <font class='italic' color='purple'>location cycle-type &optional n-words</font>
  </font><br>
This turns off the MAR.  Restarting the machine disables the
MAR but does not turn it off, i.e. references to the MARed pages
are still slowed down.  <!-- open: 131, close: 130 --><font class="lisp">clear-mar</font><!-- open: 131, close: 131 --> <!-- MATCHED MATCHED MATCHED --> does not currently speed
things back up until the next time the pages are swapped out;
this may be fixed some day.
</div>

<div class='defvar' id='si:%mar-low'><font class='exdent'><font class='funcname' id='si:%mar-low'>si:%mar-low</font><font class="italic"> Variable</font><br></font><!-- end font_exdent -->.defvar1 si:%mar-high
	These two fixnums are the inclusive boundaries of the area
of memory monitored by the MAR.  The values of these variables live
inside the microcode.
</div>

<div class='defun' id='mar-mode'>
  <font class='exdent'>
    <font class='funcname'>mar-mode </font>
    <font class='italic' color='purple'>location cycle-type &optional n-words</font>
  </font><br>
<!-- open: 132, close: 131 --><font class="lisp">(mar-mode)</font><!-- open: 132, close: 132 --> <!-- MATCHED MATCHED MATCHED --> returns a symbol indicating the current state of
the MAR.  It returns one of:
<table>
<tr valign='top'>
<td><font class='lisp'> nil</font></td><td>The MAR is not set.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> :read</font></td><td>The MAR will cause an error if there is a read.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> :write</font></td><td>The MAR will cause an error if there is a write.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> t</font></td><td>The MAR will cause an error if there is any reference.
</td></tr><!-- item_ --></table><!-- end table -->

</div>

Note that using the MAR makes the pages on which it is set
considerably slower to access, until the next time they are
swapped out and back in again after the MAR is shut off.
Also, use of the MAR currently breaks the read-only feature
if those pages were read-only.  Currently it is not possible
to proceed from a MAR trrap, because some machine state is lost.
Eventually, most MAR traps will be continuable.
<!-- eof -->
</body>
</html>

